home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d21 / dvglue10.arc / -DVGLUE.DOC < prev    next >
Text File  |  1988-08-13  |  60KB  |  1,369 lines
  1.                                 DV-GLUE v1.00
  2.                                 -------------
  3.                        (c) Copyright 1988  Ralf Brown
  4.                             All Rights Reserved.
  5. [See file -COPYRIT.NOT for full copying permissions/restrictions.  It
  6. basically says that you can use these functions as long as you don't try to
  7. make money or claim that you wrote them.]
  8.  
  9. DV-GLUE is a collection of some 230 functions which give your programs access
  10. to the power of the DESQview[*] and TopView[**] environments.  You may use
  11. them freely provided you do not try to make money off of the programs you
  12. write using them.  Donations are neither required nor expected (unless you're
  13. trying to make money, see -COPYRIT.NOT), but wouldn't be turned down.
  14.  
  15. DV-GLUE implements all but five of the functions described in Quarterdeck's
  16. DV API library flyer, and several dozen additional functions.
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26. ---
  27. [*] DESQview (tm) is a trademark of Quarterdeck Office Systems
  28. [**] TopView (tm) is a trademark of International Business Machines, Inc.
  29.  
  30. -----------------------------------------------------------------------------
  31. To use this library in your own programs, add the line
  32.         #include "tvapi.h"
  33. to the start of each source file using functions from the library.  If you
  34. are using constants for building your own streams, also add the line
  35.         #include "tvstream.h"
  36. to the start of the module.  If you are using any of the UI... functions,
  37. add the line
  38.         #include "tvui.h"
  39. Then add TVAPI.LIB to the list of files to compile (if you are using TCC), or
  40. add TVAPI.LIB to the .PRJ file.
  41.  
  42. If you have been using version 0.7, see -HIST for details of the massive
  43. function renamings which have taken place.  If you have been using version
  44. 0.91, there are a few more renamed functions, as well as several functions
  45. with changed parameters.
  46. -----------------------------------------------------------------------------
  47. A number of the functions at the core of this package were originally written
  48. by John Navas and have since been modified pretty much beyond recognition.  The
  49. original versions of these can be found in the file TVGLUETC.ARC on the Dog
  50. Lab BBS (415) 594-9806.
  51.  
  52.  
  53.  
  54.  
  55.  
  56.         Ralf Brown
  57.         August 10, 1988
  58.  
  59. Direct e-mail to:
  60.         ralf@cs.cmu.edu                      (Arpanet)  \
  61.         ralf%cs.cmu.edu@cmuccvma             (BITnet)    > preferred
  62.         ...!{harvard,ucbvax}!cs.cmu.edu!ralf (UUCP)     /
  63.         Ralf Brown 1:129/31                  (FIDOnet)
  64.         [No Compu$pend/$ource/GEnie accounts....]
  65. or post a message to the DESQVIEW or DR_DEBUG echomail areas on FIDOnet
  66. -----------------------------------------------------------------------------
  67.  
  68. Setup
  69. -----
  70.  
  71. Before you can call any of the functions in this library, you must first
  72. initialize the library by calling either TVinit() or DVinit().  TVinit()
  73. will allow you to use the functions which work under both TopView and
  74. DESQview, while DVinit() will also allow you to use those functions which are
  75. unique to DESQview.
  76.  
  77. At the end of the program, before exiting, you must call either TVexit() or
  78. DVexit().  If you called TVinit() at the beginning, call TVexit() at the end.
  79. If you called DVinit(), then call DVexit().
  80.  
  81. int TVinit(void)
  82.         initialize TopView interface and return TopView version as a hex
  83.         number: 0x010A == version 1.10
  84. void TVexit(void)
  85.         clean up TopView interface before terminating program.  This also
  86.         frees a number of mailboxes used as semaphores to prevent
  87.         reentrancy problems.  If you don't call it, your "common" memory
  88.         will slowly dwindle with each run of the program until the window
  89.         is closed.
  90. int DVinit(void)
  91.         initialize DESQview interface and return DESQview version as a hex
  92.         number: 0x0201 == version 2.01
  93. void DVexit(void)
  94.         clean up DESQview interface before terminating program.  Call this
  95.         function if you started your program with DVinit().
  96.  
  97. Pre-Processor #defines
  98. ----------------------
  99.  
  100. The following two predefined symbols are useful to determine whether the
  101. correct version of DV-GLUE is being used.
  102.  
  103.         DVGLUE_version          is the version number times 100
  104.         DVGLUE_versionSTR       is a string in the form "n.nn"
  105.  
  106. Low-Level Primitives
  107. --------------------
  108.  
  109. Most of the functions described in later sections call on one or more of the
  110. functions in this section.
  111.  
  112. void TVwin_stream(OBJECT window,BYTE *stream)
  113.         send the specified stream to the window.  The only restriction on the
  114.         stream is that it may not contain window-stream opcode E6h (create
  115.         new window).
  116.  
  117. OBJECT TVwin_new(OBJECT window,int rows,int cols)
  118.         create a new window of the specified dimensions which becomes a child
  119.         of the given window, and return its handle.
  120.  
  121. void TVsendmsg(int message,int modifier,OBJECT object,PARMLIST *params)
  122.         send a message with the parameters specified in "params", returning
  123.         any result values in "params".  The PARMLIST type is a struc with
  124.         two fields:
  125.             int num_args ;   /* number of parameters sent/returned */
  126.             DWORD arg[9] ;   /* up to nine args may be sent or returned */
  127.         
  128. void TVsendmsg0(int message,int modifier,OBJECT object)
  129.         send a parameterless, non-value-returning message to the specified
  130.         object.
  131.  
  132. DWORD TVsendmsg1(int message,int modifier,OBJECT object)
  133.         send a parameterless message which returns a single value to the
  134.         specified object.
  135.  
  136. Windows
  137. -------
  138.  
  139. One of the strongest features of the DESQview API is its windowing
  140. capabilities.  DV-GLUE gives you the capability to create, move, resize,
  141. color, title, and close windows, among other things.
  142.  
  143. Each window has a logical cursor which need not be in the same place as the
  144. hardware cursor--after all, the hardware cursor could be in some other
  145. program's window.  There are calls to manipulate the logical cursor and move
  146. the hardware cursor to the position corresponding to the logical cursor.
  147.  
  148. OBJECT TVwin_new(OBJECT window,int rows,int cols)
  149.         create a new window which is a child of the given window and is
  150.         "rows" high and "cols" wide.  Returns the handle of the new window.
  151.  
  152. void TVwin_free(OBJECT window)
  153.         close the specified window.
  154.  
  155. void TVwin_attach(OBJECT window)
  156.         attach the specified window to its parent window, such that when one
  157.         window is moved, the other also moves.
  158.  
  159. void TVwin_detach(OBJECT window)
  160.         detach the specified window from its parent window, such that each
  161.         window moves independently of the other.
  162.  
  163. void TVwin_clear(OBJECT window)
  164.         Erase the entire window.  Does not affect the logical cursor's
  165.         position.
  166.  
  167. void TVwin_fill(OBJECT window,char c)
  168.         Fill the entire window with the specified character.
  169.  
  170. void TVwin_attr(OBJECT window,int attr)
  171.         Set the default output attribute for the given window.
  172.  
  173. void TVwin_cursor(OBJECT window,int row,int col)
  174.         Move the window's logical cursor to the specified position.
  175.  
  176. void TVwin_hcur(OBJECT window)
  177.         Move the hardware cursor to where the window's logical cursor is.
  178.  
  179. void TVwin_repchar(OBJECT window,char c,int count)
  180.         Write the character "c" to the given window "count" times.
  181.  
  182. void TVwin_repattr(OBJECT window,int attr,int count)
  183.         Change the attribute of the next "count" characters of the given
  184.         window to "attr."
  185.  
  186. void TVwin_blanks(OBJECT window,int count)
  187.         Write the specified number of blanks to the given window.
  188.  
  189. void TVwin_lsize(OBJECT window,int rows,int cols)
  190.         Change the logical size (not the displayed size) of the given window
  191.         to be "rows" high by "cols" wide.
  192.  
  193. void TVwin_origin(OBJECT window,int row,int col)
  194.         Move the upper left corner of the visible portion of the window to
  195.         be at (row,col).
  196.  
  197. void TVwin_resize(OBJECT window,int rows,int cols)
  198.         Change the size of the given window on the screen to be "rows" high by
  199.         "cols" wide.  You need to call TVwin_redraw() to ensure that the
  200.         window's size is updated on the screen.
  201.  
  202. void TVwin_move(OBJECT window,int row,int col)
  203.         Move the given window such that its upper left corner is at
  204.         (row,col).  You need to call TVwin_redraw() to ensure that the
  205.         window's position is updated on the screen.
  206.  
  207. void TVposwin(OBJECT window,OBJECT parent,int pos,int row_offset,int col_offset)
  208.         Move the given window to a position relative to the parent window.
  209.         The values for "pos" specify both the horizontal and vertical
  210.         position: one of
  211.             PW_HCURR    current horizontal position
  212.             PW_HCENTER  centered horizontally in parent window
  213.             PW_LEFT     at left edge of parent
  214.             PW_RIGHT    at right edge of parent
  215.         ORed with one of
  216.             PW_VCURR    current vertical position
  217.             PW_VCENTER  centered vertically in parent window
  218.             PW_TOP      at top edge of parent
  219.             PW_BOTTOM   at bottom edge of parent
  220.         optionally ORed with
  221.             PW_NOREDRAW don't refresh the screen
  222.         "row_offset" and "col_offset" are then added to the position selected
  223.         by "pos".  These values are signed, so negative values move the window
  224.         up and left.
  225.  
  226.         For this function, NIL specifies the current task's main window if
  227.         given for "window", but specifies the full screen if given for
  228.         "parent".
  229.  
  230. void TVwin_minsize(OBJECT window,int rows,int columns)
  231.         Keep the user from reducing the window's size below the specified size
  232.  
  233. void TVwin_maxsize(OBJECT window,int rows,int columns)
  234.         Keep the user from increasing the window's size beyond the specified
  235.         size.
  236.  
  237. void TVwin_title(OBJECT window,char *title)
  238.         Set the window's title to the given string.
  239.  
  240. void TVwin_bottom(OBJECT window)
  241.         move the window behind all other windows belonging to the current
  242.         task.
  243.  
  244. void TVwin_top(OBJECT window)
  245.         move the window in front of all other windows belonging to the current
  246.         task.
  247.  
  248. void TVwin_topsys(OBJECT window)
  249.         move the window in front of all other windows in the system.
  250.  
  251. void TVwin_reorder(OBJECT win,unsigned first,unsigned second,...)
  252.         Put the specified window in front, with "first", "second", etc.
  253.         being put behind it.  "first", "second", etc. are the OBJSEG of
  254.         the object handle for the respective windows.
  255.  
  256. void TVwin_redraw(OBJECT window)
  257.         Update the physical screen to accurately reflect the window.
  258.  
  259. void TVredrawwin(OBJECT window)
  260.         Same as TVwin_redraw(), but uses different method to tell DESQview to
  261.         update the screen image of the window.  This method does not make the
  262.         given window active.
  263.  
  264. void TVwin_scroll(OBJECT window,int top,int left,int height,int width,int dir)
  265.         Scroll the specified region of the window's virtual screen in the
  266.         given direction.  The valid directions are
  267.                 SCRL_LEFT
  268.                 SCRL_RIGHT
  269.                 SCRL_UP
  270.                 SCRL_DOWN
  271.  
  272. int TVwin_printf(OBJECT window,char *format, ...)
  273.         Just like printf(), but writes to the specified window.  Note that
  274.         \n is not converted to \r\n, so you will have to use \r\n if you
  275.         want the remaining text to continue at the beginning of the next
  276.         line.
  277.  
  278. void TVwin_swrite(OBJECT window,char *string)
  279.         Write the string to the given window.  Note that \n is not converted
  280.         to \r\n.
  281.  
  282. void TVwin_write(OBJECT window,char *string,int len)
  283.         Write the first "len" characters of the string to the given window.
  284.  
  285. void TVwin_writeca(OBJECT window,char *chars,char *attr,int len)
  286.         Write the first "len" characters and attributes to the given window
  287.         starting at the current position of the logical cursor.
  288.  
  289. void TVwin_writea(OBJECT window,char *attr,int len)
  290.         Change the attributes of the first "len" characters from the current
  291.         cursor position to be those specified by "attr".
  292.  
  293. void TVwin_repattr(OBJECT window,int attr,int count)
  294.         change the attributes of the next "count" characters on the virtual
  295.         screen to "attr"
  296.  
  297. void TVwin_repchar(OBJECT window,int character,int count)
  298.         write "count" copies of the character to the virtual screen for the
  299.         given window.
  300.  
  301. int TVwin_read(OBJECT window,void *buffer,int maxsize)
  302.         Read the remainder of the current line in the given window, and copy
  303.         up to "maxsize" characters into the buffer.
  304.  
  305. int TVwin_nread(OBJECT window,void *buffer,int n)
  306.         Read the next "n" characters or attributes from the given window and
  307.         place them in the buffer.
  308.  
  309. void TVwin_gotoxy(OBJECT window,int x,int y)
  310.         Position windows cursor at row y and column x.
  311.  
  312. void TVwin_cursor(OBJECT window,int row,int col)
  313.         Position window's logical cursor at the given row and column.
  314.  
  315. void TVwin_color(OBJECT window,int logical_attr,int physical_attr)
  316.         Select the physical attribute for the given logical attribute.
  317.  
  318. void TVwin_frattr(OBJECT window,int attr)
  319.         set the attribute of the given window's frame.
  320.  
  321. --------------------------
  322. There are a number of switches available:
  323.  
  324. void TVwin_atread(OBJECT window,int read_attr)
  325.         If "read_attr" is nonzero, TVwin_nread() gets attributes, if
  326.         "read_attr" is zero, TVwin_nread() gets characters.
  327.  
  328. void TVwin_ctrl(OBJECT window,int ctrl)
  329.         If "ctrl" is nonzero, output to the given window will interpret
  330.         CR, LF, BS, etc.  If "ctrl" is zero, those characters will be
  331.         displayed.
  332.  
  333. void TVwin_logattr(OBJECT window,int logattr)
  334.         If "logattr" is nonzero, DESQview will translate the attributes used
  335.         for the window, i.e. the attributes become logical.  If "logattr" is
  336.         zero, then the attributes written to a window are those displayed on
  337.         the screen, i.e. physical attributes.
  338.  
  339. void TVwin_leave(OBJECT window,int leave)
  340.         If "leave" is nonzero, then writing to a window will not change the
  341.         attributes in the positions which are overwritten.  If "leave" is
  342.         zero, then characters output to the window will be given the currently
  343.         active default attribute.
  344.  
  345. void TVwin_frame(OBJECT window,int frame)
  346.         If "frame" is nonzero, then the window's frame will be displayed.
  347.         If "frame" is zero, the window will not have a frame.
  348.  
  349. void TVwin_hide(OBJECT window)
  350.         make the given window invisible
  351.  
  352. void TVwin_unhide(OBJECT window)
  353.         make the given window visible
  354.  
  355.  
  356. Query Functions
  357. ---------------
  358.  
  359. In addition to setting window characteristics, you can find out the status of
  360. most anything that you can set.
  361.  
  362. int TVqry_attr(OBJECT window)
  363.         Returns the current default character attribute for the window.
  364.  
  365. void TVqry_cursor(OBJECT window,int *row,int *column)
  366.         Returns the position of the window's logical cursor in "row" and
  367.         "column".
  368.  
  369. void TVqry_position(OBJECT window,int *row,int *column)
  370.         Returns the position of the given window in "row" and "column"
  371.  
  372. void TVqry_origin(OBJECT window,int *row,int *column)
  373.         Returns the origin of the visible portion of the window in "row" and
  374.         "column".
  375.  
  376. void TVqry_lsize(OBJECT window,int *rows,int *columns)
  377.         Returns the logical size of the window in "rows" and "columns"
  378.  
  379. void TVqry_size(OBJECT window,int *rows,int *columns)
  380.         Returns the displayed size of the window in "rows" and "columns"
  381.  
  382. void TVqry_title(OBJECT window,char *title,int size)
  383.         Returns the first "size" characters of the window's title in "title"
  384.  
  385. int TVqry_color(OBJECT win,int logical_attr)
  386.         Returns the physical attribute which the given logical attribute is
  387.         mapped to.
  388.  
  389. int TVqry_frattr(OBJECT window)
  390.         Returns the attribute of the window's frame.
  391.  
  392. int TVwin_width(OBJECT window)
  393.         Return the width of the virtual screen for the given window.
  394.  
  395. The switches which may be set can also be read:
  396.  
  397. int TVqry_atread(OBJECT window)
  398.         returns TRUE if TVwin_nread() gets attributes, FALSE if it gets
  399.         characters.
  400.  
  401. int TVqry_ctrl(OBJECT window)
  402.         returns TRUE if control characters are interpreted, FALSE if not
  403.  
  404. int TVqry_logattr(OBJECT window)
  405.         returns TRUE if logical attributes are being used, FALSE if physical
  406.         attributes are used.
  407.  
  408. int TVqry_leave(OBJECT window)
  409.         returns TRUE if writing to the window will leave the character
  410.         attributes unchanged, and FALSE if the attributes are changed to the
  411.         current default attribute.
  412.  
  413. int TVqry_frame(OBJECT window)
  414.         returns TRUE if the window has a frame, FALSE otherwise.
  415.  
  416. int TVqry_hidden(OBJECT window)
  417.         returns TRUE if the window is hidden, FALSE if it is visible.
  418.  
  419. Keyboard Objects
  420. ----------------
  421.  
  422. Keyboard objects let you direct keyboard input to a specified window, to send
  423. data that another process thinks came from the keyboard, and other things.
  424.  
  425. OBJECT TVkbd_new(void)
  426.         create a new keyboard object and return its handle.
  427.  
  428. void TVkbd_free(OBJECT kbd)
  429.         destroy keyboard object.  Do not attempt to free the default keyboard!
  430.  
  431. void TVkbd_open(OBJECT kbd, OBJECT window)
  432.         connect "kbd" to the indicated window
  433.  
  434. void TVkbd_close(OBJECT kbd)
  435.         disconnect the keyboard from its window
  436.  
  437. int TVkbd_messages(OBJECT kbd)
  438.         determine how many messages are pending for the keyboard
  439.  
  440. void TVkbd_clear(OBJECT kbd)
  441.         remove all pending messages from the keyboard
  442.  
  443. OBJECT TVmykbd(void)
  444.         return the handle of the current task's default keyboard.  For the
  445.         functions described in this section, the special handle NIL represents
  446.         the default keyboard.
  447.  
  448. OBJECT TVkbdof(OBJECT task)
  449.         return the handle for the given task's default keyboard.
  450.  
  451. int TVkbd_read(OBJECT kbd,char *buffer,int maxsize)
  452.         wait for a keyboard message on "kbd", and then fill "buffer" with up
  453.         to (maxsize-1) characters from the message.  Returns the actual size
  454.         of the message read.
  455.  
  456.         If the keyboard is in field mode, then the user can edit the input
  457.         fields at will, and the return contains the contents of all input
  458.         fields in the following format:
  459.  
  460.                 BYTE  field number
  461.                 WORD  length of field data
  462.               N BYTES contents of field
  463.  
  464.         This repeats until the field number is zero, which signals the end of
  465.         the data.
  466.  
  467. int TVkbd_status(OBJECT kbd)
  468.         return status of last message read from "kbd".  If the keyboard is in
  469.         field mode, the status will indicate how the entry was terminated.
  470.                 1  = pressed RETURN
  471.                 27 = pressed ESC
  472.  
  473. void TVkbd_write(OBJECT kbd,char *data,int size,int status)
  474.         write a message of the given size to "kbd", using the given status,
  475.         which may then be checked by the reader with TVkbd_status().
  476.  
  477. void TVkbd_setflags(OBJECT kbd,int flags)
  478.         set the keyboard behavior flags for "kbd" that correspond to the set
  479.         bits of "flags"
  480.  
  481.         Valid flags (OR together):
  482.            KBD_FIELDMODE        put keyboard into field mode
  483.            KBD_ACTIVE           keyboard is active in "kbd"s window
  484.            KBD_INSERT           keyboard is in "insert" mode
  485.            KBD_CONCURRENT       program continues running during input
  486.            KBD_FILTERALL        filter all keystrokes through TVkbd_setesc
  487.                                 handler
  488.  
  489. void TVkbd_clrflags(OBJECT kbd,int flags)
  490.         clear the keyboard behavior flags for "kbd" that correspond to the set
  491.         bits of "flags".  The valid flags are the same as for TVkbd_setflags.
  492.  
  493. void TVkbd_setesc(OBJECT kbd,void far (*func)(void))
  494.         set a keyboard filtering function.  Not yet tested.
  495.  
  496. Timers
  497. ------
  498.  
  499. The timer management functions allow you to create, destroy, set, and read
  500. timer objects which can provide for delays.
  501.  
  502. OBJECT TVtimer_new(void)
  503.         create a new timer object and return its handle
  504.  
  505. OBJECT TVtimer_free(void)
  506.         destroy a timer object and return its memory to the common pool
  507.  
  508. void TVtimer_begin(OBJECT timer,DWORD length)
  509.         start a timer counting down from "length".  The timer will run for
  510.         10 * length milliseconds (though the timer's resolution is actually
  511.         only 55 milliseconds).
  512.  
  513. void TVtimer_set(OBJECT timer,int hour,int minute,int second,int hundredths)
  514.         Start a timer counting down such that it finishes at the indicated
  515.         time.
  516.  
  517. DWORD TVtimer_len(OBJECT timer)
  518.         return the amount of time left on the timer.
  519.  
  520. DWORD TVtimer_elapsed(OBJECT timer)
  521.         return the amount of time elapsed since the timer was started.
  522.  
  523. void TVtimer_start(OBJECT timer)
  524.         start the timer counting down
  525.  
  526. void TVtimer_stop(OBJECT timer)
  527.         stop the timer from counting down
  528.  
  529. void TVtimer_close(OBJECT timer)
  530.         close the timer object.  Also stops the countdown.
  531.  
  532. DWORD TVtimer_wait(OBJECT timer)
  533.         wait until the timer completes its countdown, and return the time in
  534.         1/100ths seconds since midnight at the time the counter finished.
  535.  
  536. int TVtimer_status(OBJECT timer)
  537.         find out whether the timer is running or not.
  538.  
  539. Pointers
  540. --------
  541.  
  542. OBJECT TVptr_new(void)
  543.         creates a new pointer object and returns its handle
  544.  
  545. void TVptr_free(OBJECT pointer)
  546.         destroy the given pointer object
  547.  
  548. void TVptr_open(OBJECT pointer, OBJECT window)
  549.         connect the mouse pointer to the given window, where NIL means the
  550.         current task's default window
  551.  
  552. void TVptr_close(OBJECT pointer)
  553.         disconnect the mouse pointer from its window
  554.  
  555. void TVptr_icon(OBJECT pointer,char symbol)
  556.         set the character used to represent the mouse pointer.
  557.  
  558. void TVptr_goto(OBJECT ptr,int row,int col)
  559.         move the mouse pointer to the given position relative to the window's
  560.         upper left corner
  561.  
  562. void TVptr_setflags(OBJECT pointer,WORD flags)
  563.         set pointer behavior flags.  The valid flags (OR together) are:
  564.                 PTR_BUTTON      only report on button activity (requires a
  565.                                 previous call to DVenable())
  566.                 PTR_RELEASE     report on button release as well as press
  567.                 PTR_ABSOLUTE    pointer coordinate relative to phys screen
  568.                 PTR_SLOWCLICK   button held 1/2 sec before it "click"s.  Used
  569.                                 to allow chords to be pressed.
  570.                 PTR_NOTFORE     report even is window is not in foreground
  571.                 PTR_NOTTOP      report even if window in not topmost
  572.                 PTR_HIDDEN      mouse pointer is invisible inside window
  573.  
  574. void TVptr_clrflags(OBJECT pointer,WORD flags)
  575.         clear pointer behavior flags.  What the flags are is not yet known.
  576.  
  577. void TVptr_erase(OBJECT pointer)
  578.         discard all unread pointer messages
  579.  
  580. int TVptr_messages(OBJECT pointer)
  581.         return the number of unread pointer messages
  582.  
  583. int TVptr_read(OBJECT window,POINTER_MSG *msg)
  584.         wait for the next pointer message, and put it in "msg"
  585.         Returns 0 on success, -1 on error.
  586.  
  587.         The format of the POINTER_MSG is:
  588.                 int row ;
  589.                 int column ;
  590.                 BYTE button_state
  591.         Valid bits in button_state are:
  592.                 BUTTON_PRESS       \ only available if pointer flag PTR_RELEASE
  593.                 BUTTON_RELEASE     / is set
  594.                 BUTTON_LEFT
  595.                 BUTTON_RIGHT
  596.  
  597. int TVptr_status(OBJECT pointer)
  598.         return the pointer's status.  This value is the same as the
  599.         button_state field of POINTER_MSG (see above).
  600.  
  601. void TVptr_goto(OBJECT ptr,int row,int col)
  602.         move the mouse pointer to the given position relative to the window's
  603.         upper left corner
  604.  
  605. void TVptr_setscale(OBJECT pointer,int rows,int cols)
  606.         Set the scaling of the pointer's coordinates such that the window it
  607.         has been connected to with TVptr_open() is considered to be "rows"
  608.         high and "cols" wide.
  609.  
  610. void TVptr_getscale(OBJECT pointer,int *rows,int *cols)
  611.         returns the scaling factors previously set with TVptr_setscale().
  612.  
  613. void TVwin_point(OBJECT window,OBJECT pointer)
  614.         move the mouse pointer to the location of the given window's logical
  615.         cursor.
  616.  
  617. Keyboard Mouse
  618. --------------
  619.  
  620. For those systems without a mouse attached, DESQview provides a "keyboard
  621. mouse" which emulates a mouse using the numeric keypad.  There are two
  622. functions relating to the keyboard mouse:
  623.  
  624. int TVqry_kmouse(void)
  625.         returns TRUE if DESQview is using a keyboard mouse, FALSE if not
  626.  
  627. void TVapi_kmouse(int active)
  628.         if "active" is TRUE, turn on the keyboard mouse, if it is FALSE
  629.         turn off the keyboard mouse.
  630.  
  631. Panel Files
  632. -----------
  633.  
  634. I have no idea what the format of panel files is, so I have no way to test
  635. the panel functions.  I do know that TVpanel_new(), TVpanel_free(),
  636. TVpanel_open(), and TVpanel_close() *appear* to work.
  637.  
  638. OBJECT TVpanel_new(void)
  639.         create a new panel object and return its handle
  640.  
  641. void TVpanel_free(OBJECT panel)
  642.         destroy the panel object
  643.  
  644. void TVpanel_open(OBJECT panel,char *filename)
  645.         associate the panel object with a disk file
  646.  
  647. void TVpanel_close(OBJECT panel)
  648.         close the panel file on disk
  649.  
  650. DWORD TVpanel_status(OBJECT panel)
  651.         check whether panel object is associated with a file?
  652.  
  653. int TVpanel_size(OBJECT panel)
  654.         return the number of panels in the panel file
  655.  
  656. char far * TVpanel_dir(OBJECT panel, int *num_entries)
  657.         get the directory of panels in the panel file.  I have no idea
  658.         what the format of the directory entries is.
  659.  
  660. void TVpanel_apply(OBJECT panel,char *name,OBJECT window)
  661.         write the named panel from the panel file to the given window.  If
  662.         "window" is NIL, then
  663.  
  664.  
  665.  
  666.  
  667. Object Queues
  668. -------------
  669.  
  670. Object queues let you wait for any one of multiple occurrences without
  671. creating a separate task for each, and without polling for them.
  672.  
  673. void TVobq_add(OBJECT objectq, OBJECT item)
  674.         add the specified object to the given objectq.  Using NIL for the
  675.         objectq will use the current task's objectq.
  676.  
  677. void TVobq_remove(OBJECT objectq, OBJECT item)
  678.         remove the specified object from the queue.
  679.  
  680. void TVobq_clear(OBJECT objectq)
  681.         remove ALL objects from the queue.
  682.  
  683. int TVobq_size(OBJECT objectq)
  684.         return the number of items in the specified queue.
  685.  
  686. DWORD TVobq_status(OBJECT objectq)
  687.         find out whether or not the object queue is open
  688.  
  689. void TVobq_open(OBJECT objectq)
  690.         open the given objectq.  NIL means the current task's objectq.
  691.  
  692. void TVobq_close(OBJECT objectq)
  693.         close the given objectq.  NIL means the current task's objectq.
  694.  
  695. OBJECT TVmyobq(void)
  696.         return the handle of the current task's objectq.
  697.  
  698. OBJECT TVobqof(OBJECT task)
  699.         return the handle of the given task's objectq.
  700.  
  701. OBJECT TVobq_read(OBJECT objectq)
  702.         wait for any object on the queue to have input, and return the handle
  703.         of the object which has input.
  704.  
  705. Multiple Threads of Execution
  706. -----------------------------
  707.  
  708. The task management functions allow you to create and destroy threads, and
  709. start, stop, and interrupt other threads.
  710.  
  711. OBJECT TVtask_new(OBJECT parent,char *title,int row,int col,int rows,int cols,
  712.                   char *stack,int stacksize,void (*startaddr)(int),
  713.                   int switch_menu)
  714.         create a new thread as a child of "parent", whose window has title
  715.         "title" (or the title of the parent, if title == NULL).  The window
  716.         will the at (row,col) and will be "rows" lines high by "cols" columns
  717.         wide.  If stack == NULL, a stack of size "stacksize" will be malloc'd,
  718.         otherwise the given stack will be used by the new task.  The task will
  719.         begin by executing the function "startaddr", passing in the segment of
  720.         its parent task's handle.
  721.  
  722.         If "rows" is negative, then the window will have the same number of
  723.         rows as the parent window; similarly for "cols".  If both "rows"
  724.         and "cols" are zero, no new window will be created.
  725.  
  726.         If "switch_menu" is TRUE, the new task will be placed on the Switch
  727.         Windows menu.
  728.  
  729. void TVtask_free(OBJECT task)
  730.         kill the given task.
  731.  
  732. void TVforeonly(OBJECT task,int foreonly)
  733.         Sets whether or not a task will run in the background.  If "foreonly"
  734.         if nonzero, the task will be suspended while in the background.
  735.  
  736. OBJECT TVmytask(void)
  737.         return the handle of the currently executing task
  738.  
  739. void TVinterrupt(OBJECT task,void far (*func)(void))
  740.  
  741. void TVtask_stop(OBJECT task)
  742.         suspend the given task.  At least in DV 2.00, this call is ignored
  743.         unless the given task is the currently executing one.
  744.  
  745. void TVtask_start(OBJECT task)
  746.         restart the previously suspended task
  747.  
  748. void TVtask_post(OBJECT task)
  749.         start the given task and add its handle to the current task's objectq
  750.  
  751. WARNING:  If you use multiple threads, you will have to ensure that library
  752. routines which are not completely reentrant have a guarded replacement which
  753. waits until any other threads have exited the function.  By default,
  754. TVAPI.H contains #define's to protect malloc(), calloc(), realloc(), and free().
  755. Other functions to watch out for are rand(), srand(), ...printf(), and
  756. ...scanf().
  757.  
  758. Applications
  759. ------------
  760.  
  761. Applications are very similar to threads, except that each application has its
  762. own code and data within a memory partition, and may contain multiple threads.
  763. When a thread is started, it inherits the code of its parent; when an
  764. application is started, it gets new code from an executable on disk.
  765.  
  766. OBJECT TVapp_new(OBJECT win,int row,int col,int rows,int cols,int switch_menu,
  767.                  char *program, char *argv0, char *argv1, ..., NULL )
  768.         Start a new application as a child of the task owning "win".  The
  769.         new window will be at (row,col) and will be rows by cols in size.
  770.         Load "program", and start it executing with the remaining arguments as
  771.         command line.  If "switch_menu" is TRUE, the program will be listed
  772.         on the Switch Windows menu.
  773.  
  774. OBJECT DVapp_start(void *pif_file, int pif_size)
  775.         Given the contents of the .PIF or .DVP file, start a new application in
  776.         a completely new memory partition.  This function is known to cause
  777.         lockups under DV 2.00 (6-16-87).  Use at your own risk (though I would
  778.         appreciate hearing from you which version (and date) you are using and
  779.         whether or not it worked).
  780.  
  781. void TVapp_free(OBJECT app)
  782.         kill the given application.
  783.  
  784. void TVapp_goback(OBJECT app)
  785.         force the given application into the background
  786.  
  787. void TVapp_gofore(OBJECT app)
  788.         force the given application into the foreground
  789.  
  790. void TVapp_suspend(OBJECT app)
  791.         hide all windows belonging to the given application and suspend it.
  792.  
  793. void TVapp_hide(OBJECT app)
  794.         hide all windows belonging to the given application.  The application
  795.         continues to run.
  796.  
  797. void TVapp_show(OBJECT app)
  798.         show the windows belonging to the given application.
  799.  
  800. Mailboxes
  801. ---------
  802.  
  803. Mailboxes provide a convenient way for different tasks to communicate.
  804. Each task gets a mailbox by default, and this is the mailbox to which
  805. asynchronous notification messages are sent (see a later section).
  806.  
  807. OBJECT TVmbx_new(void)
  808.         create a new mailbox and return its handle
  809.  
  810. void TVmbx_open(OBJECT mbx)
  811.         open a mailbox, making it available for messages.  A task's default
  812.         mailbox is opened for you.
  813. void TVmbx_close(OBJECT mbx)
  814.         close a mailbox, making it unavailable.
  815.  
  816. void TVmbx_free(OBJECT mbx)
  817.         destroy a mailbox object and return its memory to the pool of common
  818.         memory.  Do not use this function on a task's default mailbox, as
  819.         the mailbox's memory is part of the task object's memory block.
  820.  
  821. OBJECT TVmymbx(void)
  822.         return handle for current task's default mailbox.  Note that all of
  823.         the functions expecting a mailbox handle will accept NIL for the
  824.         default mailbox.
  825. OBJECT TVmbxof(OBJECT task)
  826.         return the given task's default mailbox.  This is useful for sending
  827.         mail to another task, such as a subtask you have created.
  828.  
  829. void TVmbx_name(OBJECT mbx,char *name)
  830.         give a mailbox a globally visible name.  Using the next function,
  831.         anyone can then find the mailbox knowing only the name.
  832. OBJECT TVmbx_find(char *name)
  833.         find the mailbox with the given name.  Returns NIL if there is no
  834.         mailbox with that name.
  835.  
  836. void TVmbx_clear(OBJECT mbx)
  837.         discard all pending messages from the mailbox.
  838.  
  839. int TVmbx_size(OBJECT mbx)
  840.         return the number of pending messages in the mailbox
  841.  
  842. int TVmbx_status(OBJECT mbx)
  843.         return the status of the last message read
  844.  
  845. void TVmbx_write(OBJECT mbx,int ref,int status,char *msg,int length)
  846.         send the message "msg" with the given length to the mailbox
  847.         "mbx".  The status is set to "status", and the message is passed by
  848.         reference if "ref" is nonzero, and by value (i.e. a copy is made)
  849.         if "ref" is zero.
  850.  
  851. void TVsendmail(OBJECT mbx,char *msg,int length)
  852.         send the message "msg" with the given length of the mailbox
  853.         "mbx".  The status is set to zero, and the message is passed by
  854.         value (i.e. a copy is made).
  855.  
  856. int TVreadmail(OBJECT mbx,char *buffer,int maxsize)
  857.         wait for a message to arrive in the mailbox, and then fill buffer
  858.         with up to (maxsize-1) characters of the message.  Returns the actual
  859.         size of the message read.
  860.  
  861. There are also two functions which use mailboxes to synchronize access to
  862. resources, in effect treating the mailbox as a semaphore:
  863.  
  864. void TVlock(OBJECT mbx)
  865.         request exclusive access to resource.  If another task has already
  866.         locked the mailbox, the current task will be halted until the other
  867.         task unlocks the mailbox.  It is legal to lock the mailbox multiple
  868.         times, in which case you must unlock it the same number of times that
  869.         you locked it.
  870. void TVunlock(OBJECT mbx)
  871.         release exclusive access to resource.  If this unlocking corresponds
  872.         to the last lock placed on the mailbox, then any other task waiting to
  873.         lock the mailbox may proceed.
  874.  
  875. Fields
  876. ------
  877.  
  878. Fields are used in building a data-input screen which can be filled out by the
  879. user.  After setup, a single call lets the user fill out the entire screen,
  880. after which the results can be read back.
  881.  
  882. void TVfld_header(OBJECT win,FT_HEADER header)
  883.         sets the field table header which defines how many fields there are,
  884.         the colors of the current field and selected fields, and the type of the
  885.         screen.
  886.  
  887.         The FT_HEADER structure contains the following fields:
  888.              BYTE numfields      the number of fields on the screen
  889.              BYTE type           behavior flags, see TVfld_build_header
  890.              BYTE curr_attr      attribute of current field during input
  891.              BYTE selected_attr  attribute of any selected fields
  892.              int unknown         must be zero
  893.  
  894. void TVfld_entry(OBJECT win,int field,FT_ENTRY entry)
  895.         sets up the specified field, indicating its position and type.
  896.  
  897.         The FT_ENTRY structure contains the following fields
  898.              BYTE upleftrow    \ row and column of upper left corner
  899.              BYTE upleftcol    /
  900.              BYTE lowrightrow  \ row and column of lower right corner
  901.              BYTE lowrightcol  /
  902.              BYTE type           type of the field, see TVfld_build_entry()
  903.              BYTE modifier       type modifier, see TVfld_build_entry()
  904.              BYTE status         don't quite know what this does
  905.              BYTE key2           second key of a two-key menu entry
  906.  
  907. BYTE *TVfld_build_header(int num_fields,int screen_type,
  908.                          int curr_attr,int selected_attr)
  909.         begins building a stream for a screen with "num_fields" fields, using
  910.         the given screen type, where the current field will have attribute
  911.         "curr_attr" and any selected fields will have attribute
  912.         "selected_attr".  All fields will have attribute "curr_attr" by
  913.         default, but this may be changed with TVfld_build_color() ;
  914.         Use TVfld_build_entry() and TVfld_build_color() to set the field
  915.         sizes and colors, and then use TVwin_stream(window,stream) to
  916.         send the stream to the window for which you want to define fields.
  917.         DO NOT FREE THE STREAM UNTIL AFTER YOU HAVE FINISHED A TVkbd_read()
  918.         ON THE WINDOW.
  919.  
  920.         The following behaviors may be ORed together for the screen type:
  921.                 F_NOREAD        TVkbd_read() returns no data
  922.                 F_READARRAY     read returns a packed array of chars
  923.                 F_READALL       read returns var-length records of all fields
  924.                 F_READNEW       read returns var-length records of modified
  925.                                 fields
  926.                 the above are mutually exclusive
  927.                 F_NOFLAGS       menu items returned as ' ' instead of 'Y'/'N'
  928.                 F_RIGHTBUTTON   right mouse button terminates entry
  929.                 F_LEFTBUTTION   left mouse button terminates entry
  930.                 F_ALLOWKBD      menu choices may be made by keystrokes
  931.  
  932. void TVfld_build_entry(BYTE *stream,int field,int upleftrow,int upleftcol,
  933.                        int lowrightrow,int lowrightcol,int type,int modifier,
  934.                        int status,int key2)
  935.         Define the given field (numbered from 1 to the number of fields) to
  936.         be the rectangle from (upleftrow,upleftcol) to
  937.         (lowrightrow,lowrightcol).  Use the specified type of field (see
  938.         below), with the given modifier and status.  "key2" should be zero
  939.         unless this is a menu entry that uses two keystrokes to select.
  940.  
  941.         The legal types of fields are
  942.                 F_NONENTRY   no entries allowed on this field
  943.                 F_MENUECHO   place where keystrokes for a two-key menu are put
  944.                 F_FILLIN     fill-in-the-blank field
  945.                 F_MENU       menu selection
  946.  
  947.         For type F_FILLIN, the legal modifiers (OR together) are:
  948.                 F_BEEP       beep when field is full
  949.                 F_NEXT       move to next field when field is full
  950.                 F_NUMBER     enter text from right to left, for numbers
  951.                 F_UPPER      force input to uppercase
  952.                 F_CLEAR      clear old field contents on first keystroke
  953.         For type F_MENU, the modifier is the first keystroke of the menu
  954.         entry, or 0 if the selection must be made with the mouse.
  955.  
  956.         If the type of the field is F_MENU, then "status" is the attribute
  957.         to use when the mouse pointer is in the field.
  958.          
  959. void TVfld_build_color(BYTE *stream,int field,int attr)
  960.         given the stream built by TVfld_build_header() and TVfld_build_entry(),
  961.         set the attribute of the given field.  Field numbers range from 1 of
  962.         the number of fields given to TVfld_build_header().
  963.  
  964. void TVfld_clear(OBJECT win,int field)
  965.         clears specified field to all blanks
  966.  
  967. void TVfld_char(OBJECT win,int field,int c)
  968.         fills the entire field with the specified character.
  969.  
  970. void TVfld_attr(OBJECT win,int field,int attr)
  971.         sets the display attribute of the specified field.
  972.  
  973. int TVfld_swrite(OBJECT win,int field,char *s)
  974.         write the characters of the string "s" to the specified field.
  975.         If the string is shorter than the field, the rest of the
  976.         field is padded with blanks.  Returns TRUE if the string could
  977.         be written, FALSE otherwise.
  978.  
  979. int TVfld_write(OBJECT win,int field,char *s)
  980.         write EXACTLY enough characters of the string "s" to the specified
  981.         field in order to fill it.  Returns TRUE if the string could be written,
  982.         FALSE otherwise.
  983.  
  984. void TVfld_cursor(OBJECT win,int field)
  985.         move the cursor to the specified field
  986.  
  987. void TVfld_scroll(OBJECT window,int field,int direction)
  988.         scroll the given field on the window one position in the specified
  989.         direction.  Legal directions are SCRL_UP, SCRL_DOWN, SCRL_LEFT,
  990.         and SCRL_RIGHT.
  991.  
  992. void TVfld_type(OBJECT window,int field,int type)
  993.         Set the field's type.  Legal types are F_NONENTRY, F_MENUECHO,
  994.         F_FILLIN, and F_MENU.  See TV_fld_build_entry() above.
  995.  
  996. void TVfld_reset(OBJECT window)
  997.         Resets selected and modified bits on all field for the window.
  998.  
  999. void TVfld_marker(OBJECT window,char marker)
  1000.         Sets the character to display at the left edge of fields which have
  1001.         their "selected" bit set.
  1002.  
  1003. void TVfld_altmode(OBJECT keyboard,int altmode)
  1004.         If "altmode" is TRUE, set the keyboard into field mode.  If "altmode"
  1005.         is FALSE, set the keyboard into character mode.
  1006.  
  1007. unsigned TVqry_fieldsize(OBJECT window,int field)
  1008.         return the size in characters of the specified field on the window.
  1009.  
  1010. int TVqry_field(OBJECT window,int field,int buffersize,char *buffer)
  1011.         put up to "buffersize" characters of the specified field on the given
  1012.         window into the buffer.  Return TRUE if the read was successful,
  1013.         FALSE if not.
  1014.  
  1015. void TVqry_header(OBJECT window,FT_HEADER *header)
  1016.         fill in "header" with the field table header, which indicates
  1017.         the number of field and other information.  See TVfld_header()
  1018.         above for the format of the FT_HEADER structure.
  1019.  
  1020. void TVqry_entry(OBJECT window,int field,FT_ENTRY *entry)
  1021.         fill in "entry" with the specified field table entry.  See
  1022.         TVfld_entry() above for the format of the FT_ENTRY structure.
  1023.  
  1024. int TVqry_type(OBJECT window,int field)
  1025.         return the type byte of the specified field on the window.  This byte
  1026.         is also returned by TVqry_entry() as part of the field table entry.
  1027.  
  1028. Asynchronous Notification
  1029. -------------------------
  1030.  
  1031. A program running under DESQview may request to be notified when certain
  1032. events occur.  When a selected event occurs, the specified handler is
  1033. immediately invoked, and a message is sent to the task's default mailbox
  1034. indicating which event occurred.
  1035.  
  1036. void TVwin_async(OBJECT win,void far (*func)(void))
  1037.         Defines a notification handler for the window "win".  You may share a
  1038.         handler among multiple windows, as the events which apply to a single
  1039.         window identify which window was affected.
  1040.  
  1041.         Note: while inside the handler, the task's private stack will be in
  1042.         use, and you can't use TVostack() or TVustack() to switch stacks, as
  1043.         they mess up DESQview's record of its own stack use.  As the stack is
  1044.         only 256 bytes, and some of that is used by DESQview, you will very
  1045.         quickly run out of space.
  1046.  
  1047.         This function will not work in huge model at present.  A supporting
  1048.         function would have to be recoded entirely in assembler to get around
  1049.         the huge model function entry code.
  1050.  
  1051. void TVwin_notify(OBJECT win,int event)
  1052.         Call the notification handler set up with TVwin_async() on the
  1053.         specified event.  The events are defined in TVSTREAM.H and are:
  1054.                 TV_HMOVE          window was moved left or right
  1055.                 TV_VMOVE          window was moved up or down
  1056.                 TV_HSIZE          window's width changed
  1057.                 TV_VSIZE          window's height changed
  1058.                 TV_HSCROLL        window was scrolled left or right
  1059.                 TV_VSCROLL        window was scrolled up or down
  1060.                 TV_CLOSE          window is requested to close itself
  1061.                 TV_HIDE           window was hidden
  1062.                 TV_HELP           DESQview main menu "Help for Program" selected
  1063.                 TV_COLORS         DESQview "Rearrange" menu "Colors" option
  1064.                 TV_RAISE          window was put in foreground
  1065.                 TV_LOWER          window was put in background
  1066.                 TV_VIDEOMODE      "Rearrange" "Video Options" selected
  1067.                 TV_SCISSORS_CUT   "Scissors" menu "Cut" option selected
  1068.                 TV_SCISSORS_COPY  "Scissors" menu "Copy" option selected
  1069.                 TV_SCISSORS_PASTE "Scissors" menu "Paste" option selected
  1070.                 TV_MAINMENU       DESQview main menu popped up
  1071.                 TV_MENU_END       DESQview main menu closed
  1072.  
  1073. void TVwin_cancel(OBJECT win,int event)
  1074.         Turn off notification of given event for the window "win".  The events
  1075.         are the same as for TVwin_notify().
  1076.  
  1077. void TVwin_allow(OBJECT win,int event)
  1078.         Allow the specified event to occur on the window "win".  The possible
  1079.         events are defined in TVSTREAM.H and are
  1080.                 TV_HMOVE        horizontal movement of the window
  1081.                 TV_VMOVE        vertical movement of the window
  1082.                 TV_HSIZE        changing the width of the window
  1083.                 TV_VSIZE        changing the height of the window
  1084.                 TV_HSCROLL      scrolling the window left or right
  1085.                 TV_VSCROLL      scrolling the window up or down
  1086.                 TV_CLOSE        main menu "Close" option
  1087.                 TV_HIDE         allow DESQview "Rearrange" menu "Hide" option
  1088.                 TV_MARK         access to DESQview's "Mark" menu
  1089.                 TV_SCISSORS     access to DESQview's "Scissors" menu
  1090.                 TV_MAINMENU     allow DESQview's main menu to pop up
  1091.                 TV_SWITCH       allow switching to other window
  1092.                 TV_OPENMENU     allow access to DESQview's "Open" menu
  1093.                 TV_QUIT         allow DESQview main menu "Quit" option
  1094.  
  1095. void TVwin_disallow(OBJECT win,int event)
  1096.         disallow the given event for the window "win".  The events are the
  1097.         same as for TVwin_allow().
  1098.  
  1099. NOTE:  if a function is not completely reentrant, you may not use that
  1100. function within a notification handler unless the function cannot be called in
  1101. any code from which the notification may take place.  If you are using a
  1102. guarded replacement (for functions such as malloc() and free()), you must
  1103. still follow this restriction, as you may otherwise hang the current process.
  1104.  
  1105. In addition, small-model code which assumes SS == DS (which some C library
  1106. functions do) will break, as SS will be different inside the notification
  1107. handler.
  1108.  
  1109. Second-Level Interrupts
  1110. -----------------------
  1111.  
  1112. WORD TVgetbit(void far (*handler)(void))
  1113.         allocate a second-level interrupt, and set it to point to "handler"
  1114.         Returns a bitmask with a single bit set, or 0 if no second-level
  1115.         interrupt could be allocated.
  1116.  
  1117. void TVsetbit(WORD bitmask)
  1118.         enqueue all second-level interrupts corresponding to set bits in the
  1119.         bitmask.
  1120.  
  1121. void TVfreebit(WORD bitmask)
  1122.         deallocate all second-level interrupts corresponding to set bits in
  1123.         the bitmask.
  1124.  
  1125. Memory Allocation
  1126. -----------------
  1127.  
  1128. There are a number of functions to allocate and deallocate blocks of common
  1129. memory, and find out how much memory is available.
  1130.  
  1131. void DVcommon_mem(WORD *avail, WORD *largest, WORD *total)
  1132.         sets "avail" to the total bytes of common memory available
  1133.         sets "largest" to the number of bytes in the largest block of common
  1134.                 memory available
  1135.         sets "total" to the total number of bytes of common memory
  1136.  
  1137. void DVconv_mem(WORD *avail, WORD *largest, WORD *total)
  1138.         sets "avail" to the total kilobytes of conventional memory available
  1139.         sets "largest" to the size in K of the largest block of conv memory
  1140.         sets "total" to the total size of conventional memory in K
  1141.  
  1142. void DVexp_mem(WORD *avail, WORD *largest, WORD *total)
  1143.         same as DVconv_mem, except that it reports on expanded memory
  1144.  
  1145. void far *TVgetmem(unsigned amt)
  1146.         allocate "amt" bytes of system memory and return a pointer to the
  1147.         allocated block.
  1148.  
  1149. void TVputmem(void far *block)
  1150.         return the previously allocated block of system memory to the pool
  1151.         of available memory.
  1152.  
  1153. Miscellaneous Functions
  1154. -----------------------
  1155.  
  1156. void TVpause(void)
  1157.         give up rest of timeslice to other tasks/processes
  1158.  
  1159. void TVbegincrit(void)
  1160. void TVendcrit(void)
  1161.         delimit a "critical section", during which TopView/DESQview will not
  1162.         perform task switches.
  1163.  
  1164. void TVostack(void)
  1165.         switch to task's private stack
  1166. void TVustack(void)
  1167.         switch back to user stack
  1168.  
  1169.         Use extreme caution with these two functions, as they switch the stack
  1170.         out from under your C code.  You will not be able to access local
  1171.         variables after the stack switch, and any code which assumes SS == DS
  1172.         will break.
  1173.  
  1174. void far *TVshadow(void)
  1175.         returns address of shadow buffer for the current task's main window.
  1176.         Under DESQview, it also starts shadowing, that is, automatically
  1177.         updating the display.  Under TopView, you must manually update the
  1178.         display with the next function.
  1179. void TVupdate(void far *first, WORD count)
  1180.         update the display from the shadow buffer, starting with the character
  1181.         pointed to by "first", for "count" contiguous characters
  1182.  
  1183. void far *DVshadow_start(int *rows,int *cols)
  1184.         similar to TVshadow(), but also returns size of shadow buffer in rows
  1185.         and columns.  Unlike TVshadow(), it will restart shadowing which has
  1186.         been stopped by TVupdate() or DVshadow_stop().
  1187. void DVshadow_stop(void)
  1188.         stop automatic updating of screen from shadow buffer.  In DESQview 2.0
  1189.         and higher, shadowing is also stopped by TVupdate(), but will not be
  1190.         restarted by TVshadow().
  1191.  
  1192. int DVappnum(void)
  1193.         returns the number of the current task as it appears on the "Switch
  1194.         Windows" menu.
  1195.  
  1196. WORD DVprogname(void)
  1197.         returns the offset within DESQVIEW.DVO of the current task's name.
  1198.  
  1199. void DVdbgpoke(char c)
  1200.         write the character directly to the 25th line of the screen.  After
  1201.         the character is written, the next call will place the character in
  1202.         the next position, wrapping back to the beginning of the 25th line
  1203.         if necessary.  Note that this function does not heed any windows which
  1204.         may be on the screen, nor does it work properly in graphics modes.
  1205.  
  1206. void DVenable(void)
  1207.         enable DESQview extensions for the current task.  I don't yet know
  1208.         what the extent of these extensions is.
  1209.  
  1210. void DVjustify(int justify)
  1211.         if "justify" is nonzero, the viewport origins of windows will shift
  1212.         to keep the cursor within the visible portion of the virtual screen.
  1213.         If "justify" is zero, no such shifting will take place.
  1214.  
  1215. void TVgetbuf(OBJECT window,char far **buffer,int *size,int *flag)
  1216.         Get the virtual screen buffer for the given window.  On return,
  1217.         "buffer" points to the screen buffer, which contains "size" bytes.
  1218.         I don't know yet what "flag" is.
  1219.  
  1220. void TVsound(int frequency,int duration)
  1221.         make a tone with the given frequency in Hertz for the given duration
  1222.         in clock ticks (1/18 sec).  The function returns immediately, while
  1223.         the tone plays to completion.  If another tone is already playing, the
  1224.         new one is enqueued, up to 32 deep (if the queue is already full, then
  1225.         the function waits until the current tone completes before returning).
  1226.  
  1227. void TVnosound(void)
  1228.         cancel all tones queued up to be played, and turn off the current tone
  1229.         (if any).
  1230.  
  1231. User Interface Functions
  1232. ------------------------
  1233.  
  1234. The functions in this section are all high-level functions, which make use of
  1235. a number of the primitives described in previous sections.  If you wish to use
  1236. them, you must include "TVUI.H" *after* "TVAPI.H".
  1237.  
  1238. The first two functions allow you to display menus that look like the ones
  1239. DESQview itself uses.
  1240.  
  1241. void *UImenu_build(MENU_ITEM *menu_items,MENU_OPTION *menu_options)
  1242.         Build a menu stream given the description of the menu in
  1243.         "menu_items" and the title and other options in "menu_options".
  1244.         Note that the returned stream cannot be used directly because of
  1245.         control information which is added to be used by UImenu_show.
  1246.         As the memory for the stream is allocated, you should free() the
  1247.         returned menu when you are done with it.  UImenu_show() does not
  1248.         do the free() so that you may reuse the menu without having to
  1249.         rebuild it each time.
  1250.  
  1251.         Format of a menu item:
  1252.             typedef struct
  1253.                {
  1254.                char type ;      The item's type, see below
  1255.                char *entry ;    The string to display for this entry
  1256.                char key1 ;      The first key to use
  1257.                char key2 ;      The second key to use, 0 if none
  1258.                char selected ;  the field starts out selected if nonzero
  1259.                } MENU_ITEM ;
  1260.  
  1261.         Format of the menu options:
  1262.             typedef struct
  1263.                {
  1264.                char *title ;       The menu's title
  1265.                int row ;           Position of menu.  Values less than 0 are
  1266.                int col ;           measured from screen right or bottom
  1267.                int left_button ;   Can left mouse button terminate entry?
  1268.                int right_button ;  Can right mouse button terminate entry?
  1269.                int allow_kbd ;     Can menu items be selected from the kbd?
  1270.                char marker ;       Marker character for selected menu items
  1271.                } MENU_OPTIONS ;
  1272.  
  1273.         Valid menu item types:
  1274.             M_ITEM      a menu item.  The characters in "key1" and optionally
  1275.                         "key2" are placed in the "key" position on the menu.
  1276.             M_SPECIAL   a menu item using a special key.  All text after the
  1277.                         last blank is placed in the "key" position on the
  1278.                         menu.
  1279.             M_TEXT      descriptive text, will not allow entry
  1280.             M_HTEXT     highlighted descriptive text
  1281.             M_CENTER    centered descriptive text
  1282.             M_HCENTER   highlighted centered text
  1283.             M_SEP       separator line.  The character in "key1" is replicated
  1284.                         across the entire width of the menu.
  1285.             M_IGNORE    this item is completely ignored.  Useful for
  1286.                         on-the-fly addition and deletion of entries.
  1287.             M_END       indicates the end of the menu description
  1288.  
  1289.         Error returns:  UImenu_build can return three errors, and you should
  1290.         check for them before using the returned stream.
  1291.             ME_NOMEM    unable to allocate memory for the stream
  1292.             ME_TOOBIG   menu won't fit on the screen
  1293.             ME_BADITEM  invalid menu item type.  This is usually caused by
  1294.                         forgetting the M_END entry at the end of the menu
  1295.                         description.  It can also be caused by a missing
  1296.                         string for M_ITEM and a string without blanks for
  1297.                         M_SPECIAL.
  1298.  
  1299. int UImenu_show(void *menu,int reset,int (*test)(OBJECT,int,char *),char *result)
  1300.         Displays the previously built menu, resetting the "selected" flags on
  1301.         all menu items if "reset" is TRUE.  The user then selects a menu item,
  1302.         or makes some other keypress.  The test function is then called and is
  1303.         passed the handle for the menu's window,the status returned by
  1304.         DESQview (see below), and a character string indicating the state of
  1305.         each menu item.  The test function returns a value which tells
  1306.         UImenu_show() what to do next.  When the input is done, UImenu_show()
  1307.         fills in "result" with the same character string which was previously
  1308.         passed to the test function, and returns the status that was passed
  1309.         to the test function.
  1310.  
  1311.         Status:
  1312.                 0  RETURN pressed, unless a menu item defines RETURN as its
  1313.                    keypress
  1314.                 1  menu item selected by pressing left mouse button, or typing
  1315.                    the item's keystroke(s).
  1316.                 2  entry aborted with the right mouse button
  1317.                27  entry aborted by pressing ESC.
  1318.             any other value indicates the extended-ASCII value of function or
  1319.             Alt-keys which are not defined as fields and not used by DESQview
  1320.             itself.
  1321.  
  1322.         Valid test function returns.  These may be ORed together:
  1323.             MA_REDO     ask user for input again \ mutually
  1324.             MA_DONE     return to caller         / exclusive
  1325.             MA_BEEP     1/4 second beep
  1326.             MA_RESET    reset "selected" bits for all menu items
  1327.             MA_SELECT   change "selected" status of all fields to match
  1328.                         changed values in the string which was passed to the
  1329.                         test function.
  1330.  
  1331. The next function lets the user move and resize a new window by dragging it
  1332. around with the mouse.
  1333.  
  1334. OBJECT UIwin_open(OBJECT parent,int minrows,int mincols,
  1335.                   int maxrows,int maxcols,int defrows,int defcols)
  1336.         Prompt the user to use the mouse to position and size a new window,
  1337.         which defaults to "defrows" by "defcols" in size, and must be at least
  1338.         "minrows" by "mincols", but no more than "maxrows" by "maxcols."
  1339.         Returns the handle for the new window.
  1340.  
  1341. The last function (for now), is a higher-level version of TVwin_async(),
  1342. which allows a separate handler for each possible event which DESQview can
  1343. notify a program of.
  1344.  
  1345. void (*UIsignal(int signal,OBJECT win,void (*handler)()))(NOTIFY_MSG far *)
  1346.         Installs a handler for the specified event notification (the valid
  1347.         signals are the same as for TVwin_notify() and TVwin_cancel()) and
  1348.         returns a pointer to the previous handler.  The handler takes a single
  1349.         argument, which is a FAR pointer to the notification message provided
  1350.         by DESQview, with one exception.  The exception is that the first byte
  1351.         has already had the MS_NOTIFY offset subtracted from it, so the
  1352.         handler can directly compare the first byte to the event numbers
  1353.         (for those handlers that take care of multiple events).
  1354.  
  1355.         The specified event is enabled when "handler" is non-NULL, but not
  1356.         automatically disabled when "handler" is NULL.  This is because of the
  1357.         assumption that you want any event you are trapping to actually occur,
  1358.         but don't necessarily want to disable the action when you are no
  1359.         longer interested in trapping the event (such as moving the window).
  1360.         If you want the action disabled when you remove the handler, you must
  1361.         explicitly call TVwin_disallow().
  1362.  
  1363.         You may define a handler for the same signal for multiple windows, but
  1364.         only the last-used handler for a given signal is actually called,
  1365.         regardless of which window gets the notification.  BEWARE!
  1366.  
  1367.         DO NOT mix this function with the TVwin_async() function, as that
  1368.         will cause unpredictable results.
  1369.